名前¶

dbopen - データベースアクセスメソッド

書式¶

#include <sys/types.h>
#include <limits.h>
#include <db.h>
DB *dbopen(const char *file, int flags, int mode, DBTYPE type,
           const void *openinfo);

説明¶

dbopen() はデータベースファイルに対するライブラリインターフェースである。 サポートされているファイルフォーマットは btree, hash, UNIX ファイルに指向したフォーマット, の 3 つである。 btree フォーマットは、ソートされたバランスツリー構造である。 hashed フォーマットは、拡張可能な動的 hash スキームである。 フラットファイル (flat-file) フォーマットは、 固定長/可変長のレコードからなるバイトストリームファイルである。 それぞれのフォーマットと、ファイルフォーマットに特有の情報は それぞれ対応するマニュアルページ btree(3), hash(3), recno(3) に詳細に記述されている。

dbopen() は file を読み込み (読み書き) するためにオープンする。 file 引き数を NULL にすれば、 ディスク上に保存したくないファイルを作ることもできる。

flags と mode 引き数は open(2) ルーチンで指定するのと同様である。ただし 意味を持つフラグは O_CREAT, O_EXCL, O_EXLOCK, O_NONBLOCK, O_RDONLY, O_RDWR, O_SHLOCK, O_TRUNC だけである。 (注意: O_WRONLY でデータベースファイルを開く事は出来ない)

type 引き数は DBTYPE 型である (インクルードファイル <db.h> で定義されている)。 DB_BTREE, DB_HASH, DB_RECNO のいずれかをセットできる。

openinfo 引き数はアクセスメソッドに固有な構造体へのポインタである。 それぞれの構造体に関しては各アクセスメソッドの マニュアルページに記述されている。 openinfo が NULL の場合、それぞれのアクセスメソッドとシステムとに適合した デフォルトが用いられる。

dbopen() は、成功した場合 DB 構造体へのポインタを、エラーの場合 NULL を返す。 DB 構造体は <db.h> インクルードファイルの中で定義されており、 少なくとも以下のようなフィールドを持っている。

typedef struct {


    DBTYPE type;


    int (*close)(const DB *db);


    int (*del)(const DB *db, const DBT *key, unsigned int flags);


    int (*fd)(const DB *db);


    int (*get)(const DB *db, DBT *key, DBT *data,


               unsigned int flags);


    int (*put)(const DB *db, DBT *key, const DBT *data,


               unsigned int flags);


    int (*sync)(const DB *db, unsigned int flags);


    int (*seq)(const DB *db, DBT *key, DBT *data,


               unsigned int flags);
} DB;

各要素には、データベースのタイプと、 様々な動作をする関数のセットが記述されている。 これらの関数は dbopen() によって返される構造体へのポインタを引き数にとる。 キー/データ構造体へのポインタやフラグ値を取るものもある。

type

用いられているアクセスメソッド (とファイルフォーマット) の型。

close

キャッシュされた情報をディスクに掃きだすためのルーチンへのポインタ。 割り当てられたリソースを解放し、利用したファイル(群)をクローズする。 キー/データ対がメモリにキャッシュされている場合、 close や sync 関数での同期に失敗すると、情報に矛盾が生じるか情報を失う可能性がある。 close ルーチンはエラーの場合 -1 を返し (errno をセットする)、成功すると 0 を返す。

del

データベースからキー/データ対を削除するルーチンへのポインタ。

flag 引き数は次の値がセットできる。

delete ルーチンはエラーの場合 -1 を返し (errno をセットする)、成功すると 0 を返す。また指定の key がファイル中に無い場合 1 を返す。

fd

用いているデータベースのファイルデスクリプタを返すルーチン へのポインタ。 同じファイル名 file で dbopen() を呼び出した全てのプロセスに対して、 そのファイルを示す単一のファイルデスクリプタが返される。 このファイルデスクリプタはロック関数 fcntl(2) と flock(2) への引き数として安全に使用できる。 このファイルデスクリプタは、必ずしもアクセスメソッドで 用いられているファイルのいずれかに関連づけられていなくても良い。 メモリ内のデータベースにはファイルデスクリプタは無い。 fd ルーチンはエラーの場合 -1 を返し (errno をセットする)、成功するとファイルデスクリプタを返す。

get

データベースからキーを用いてデータを取り出すための ルーチンへのポインタ。 指定した key に関連づけられたデータのアドレスと長さが data が参照する構造体に返される。 get ルーチンはエラーの場合 -1 を返し (errno をセットする)、成功すると 0 を返す。また key がファイル中に無い場合 1 を返す。

put

キー/データ対をデータベースに納めるルーチンへのポインタ。

flag 引き数には次の値のうちのどれか一つがセットできる。

R_SETCURSOR は DB_BTREE と DB_RECNO アクセスメソッドでしか利用できない。 なぜなら R_SETCURSOR を用いるには、変更される事の無い固有の順序をキー が持っていなければならないからである。

R_IAFTER と R_IBEFORE は DB_RECNO アクセスメソッドでしか利用できない。 これらを実現するには、アクセスメソッドが 新しいキーを作れなければならないからである。 これが成立するのは、例えば、順序づけらた独立なレコード番号が キーになっているような場合だけである。

put ルーチンのデフォルトの動作は、新しいキー/データ対を 既に存在するキーを置き換える事て格納する動作である。

put ルーチンはエラーの場合 -1 を返し (errno をセットする)、成功すると 0 を返す。また flag に R_NOOVERWRITE がセットされていてキーが既に存在する場合 1 を返す。

seq

データベースからシーケンシャルにデータを取り出すための ルーチンへのポインタ。 キーのアドレスと長さが key が参照する構造体に返される。データのアドレスと長さが data が参照する構造体に返される。

シーケンシャルなキー/データ対の取得はいつでも行える。また 「カーソル」の位置は del, get, put, sync ルーチンの呼び出しには影響されない。 シーケンシャルなスキャンの途中に行われたデータベースへの変更は スキャンに反映される。すなわち、カーソルの後ろに挿入されたレコードは 返されないが、カーソルの前に挿入されたレコードは返される。

フラグ値には必ず以下に示すうちの どれか一つをセットしなければならない。

R_LAST と R_PREV は、 DB_BTREE と DB_RECNO アクセス方法でしか使えない。 なぜなら R_SETCURSOR を用いるには、変更される事の無い固有の順序をキーが持っていなければならないからである。

seq ルーチンはエラーの場合 -1 を返し (errno をセットする)、 成功の場合 0 を返す。 指定したキーやカレントキーよりも大きい/小さいキー/データ対がない場合は 1 を返す。 DB_RECNO アクセスメソッドを使っていて、 かつデータベースファイルが文字型のスペシャルファイルで、 完成しているキー/データ対が無い場合には、 seq ルーチンは 2 を返す。

sync

キャッシュされた情報をディスクに掃き出すルーチンへのポインタ。 データベースがメモリの中だけにある場合、 sync ルーチンは何の効果もなく常に成功する。

flag には以下の値がセットできる。

sync ルーチンはエラーの場合 -1 を返し (errno をセットする)、成功すると 0 を返す。

typedef struct {


    void  *data;


    size_t size;
} DBT;

エラー¶

dbopen() ルーチンは失敗するとライブラリルーチン open(2) と malloc(3) で指定されているエラーに応じた errno をセットする。あるいは以下をセットする。

[EFTYPE]

ファイルが正しくフォーマットされていない。

[EINVAL]

指定したパラメータ(ハッシュ関数、バイト埋めなど)が現在のファイル仕様に 合っていない、パラメータが関数にとって無意味 (例えばあらかじめ初期化しないでカーソルを使うとか)、 ファイルとソフトウェアのバージョンが合っていない。

close ルーチンは失敗するとライブラリルーチン close(2), read(2), write(2), free(3), fsync(2) で指定されているエラーに応じた errno をセットする。

del, get, put と seq ルーチンは失敗するとライブラリルーチン read(2), write(2), free(3), malloc(3) で指定されているエラーに応じた errno をセットする。

fd ルーチンはメモリ内データベースに対し失敗すると errno に ENOENT をセットする。

sync ルーチンは失敗するとライブラリルーチン fsync(2) で指定されているエラーに応じた errno をセットする。

バグ¶

typedef DBT は ``data base thang''の略語であるが、これが使われているのは、 まだ使われていない妥当な名前が思い付かなかったためである。

ファイルデスクリプタを使ったやりとりはひどい代物であり、 将来のバージョンでは削除されるだろう。

どのアクセスメソッドも、同時アクセス、ロック、トランザクション の仕組みは備えていない。

関連項目¶

btree(3), hash(3), mpool(3), recno(3)

LIBTP: Portable, Modular Transactions for UNIX, Margo Seltzer, Michael Olson, USENIX proceedings, Winter 1992.